home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 006a / gaplst13.zip / GAP_LIST.DOC < prev    next >
Text File  |  1993-04-17  |  46KB  |  1,041 lines
  1.  
  2.           
  3.  
  4.  
  5.           
  6.                   GAP_LIST - The External File Lister for GAP
  7.           
  8.           Copyright (c) 1992-1993 RoboSoft Systems. All Rights Reserved.
  9.           
  10.           
  11.           GAP_LIST is an external program used to generate file
  12.           listings for GAP BBSs.  It will allow you to easily and
  13.           quickly create file listings while you wait or in an event.
  14.           
  15.           Why do you need a program such as this when GAPFILE can
  16.           already produce file listings?  Well, to start with,
  17.           GAP_LIST was created with just one purpose in mind -- to
  18.           create file lists.  It has been highly optimized for this
  19.           specific mission.  GAP_LIST also generates all of the
  20.           requested listings with just a single pass through the
  21.           database.  What this adds up to is speed and flexibility.
  22.           On my system I can generate condensed and enhanced listings
  23.           for all areas AND for each subject in those areas, in well
  24.           under half the time it takes to do just a condensed listing
  25.           with GAPFILE.
  26.           
  27.           Here's a brief list of GAP_LIST's major features:
  28.           
  29.               - Creates Master lists of all areas and subjects
  30.                 specified in the configuration file.  
  31.               - Creates Area (Forum) lists including all subjects
  32.                 or individual subjects specified in the configuration
  33.                 file.
  34.               - Creates individual listings for each area/subject.
  35.                 (Registered version only)
  36.               - Can create separate Condensed, Enhanced, Raw, and 
  37.                 New (Registered version only) File listings in each 
  38.                 of the categories above.
  39.               - Creates a color summary bulletin listing the number
  40.                 of files and total bytes in each area and subject.
  41.               - Allows files to be excluded from the listings 
  42.                 according to security level.
  43.               - Multi-user version can be run while users are still
  44.                 online.
  45.               - Configuration file is plain ASCII so it's easy to
  46.                 change and you can have any number of different
  47.                 configurations.     
  48.                 
  49.           
  50.           GAP_LIST comes in two versions, one for single-node boards
  51.           and one for multi-node boards.  (The multi-node version is
  52.           available to registered users only.) You can use the
  53.           single-node version on multi-node boards, but you must be
  54.           sure that all nodes are inactive before running GAP_LIST.
  55.           The multi-node version allows you to generate file listings
  56.           while users are online and can be easily set up to run from
  57.           an event.  (The multi-node version requires that you have
  58.           a multi-node version of GAP.)
  59.           
  60.           
  61.           Disclaimer
  62.           ----------
  63.  
  64.  
  65.                                      Page 1                           
  66.  
  67.           GAP_LIST v1.3                                        4/17/93
  68.  
  69.  
  70.           
  71.           GAP_LIST is provided AS IS without any warranty, expressed
  72.           or implied, including, but not limited to, fitness for any
  73.           purpose.  Use of GAP_LIST, and the consequences thereof, are
  74.           entirely your risk.  In no event will RoboSoft Systems be
  75.           liable for any damages whatsoever resulting from the use of
  76.           GAP_LIST.
  77.           
  78.           
  79.           Shareware
  80.           ---------
  81.           
  82.           GAP_LIST is a Shareware product.  As such, it is made
  83.           available to the GAP sysop community for evaluation.  Users
  84.           are licensed to operate this program on their computers for
  85.           the purpose of test and evaluation on a trial basis for 30
  86.           days.  If GAP_LIST is used after the first 30 days,
  87.           registration with RoboSoft Systems is required.
  88.           
  89.           Registration
  90.           ------------
  91.           
  92.           Registered users are those users who elect to pay for
  93.           GAP_LIST and register that payment with RoboSoft Systems.
  94.           By virtue of registration and payment for the program,
  95.           registered users are granted a license to continue to
  96.           utilize the program on their personal computer for as long
  97.           as they choose.  This license authorizes use of the program 
  98.           on any personal computer system the user may own or use so 
  99.           long as the program is operated on only one computer system 
  100.           at a time.  Use on multiple systems simultaneously requires 
  101.           multiple registrations.
  102.           
  103.           The registration fee for GAP_LIST is $15.  Please make
  104.           checks payable to:
  105.           
  106.                                 RoboSoft Systems
  107.                                  P.O. Box 2221
  108.                                 Orange, CA  92669
  109.           
  110.           The payment of this registration fee to RoboSoft Systems
  111.           entitles the user to full use of GAP_LIST for an unlimited
  112.           period of time.  See the file REGISTER.DOC for complete
  113.           registration details.  Registered users receive some
  114.           additional support programs that make it easy to set up an
  115.           event that completely automates the use of GAP_LIST.
  116.           
  117.           
  118.           Updates
  119.           -------
  120.           
  121.           Updates to GAP_LIST will be provided via BBS free of charge
  122.           to registered users.  Updates on diskette are available for
  123.           a nominal charge to cover materials and handling.
  124.           
  125.           
  126.           Support
  127.           -------
  128.  
  129.  
  130.                                      Page 2                           
  131.  
  132.           GAP_LIST v1.3                                        4/17/93
  133.  
  134.  
  135.           
  136.           Support for GAP_LIST is available on The Cookie Jar BBS at
  137.           714-997-0350.  Registered users will be granted access to
  138.           the private node of the BBS and will be given priority in
  139.           having their questions answered.
  140.           
  141.           Distribution
  142.           ------------
  143.           
  144.           GAP_LIST may be freely distributed on any Bulletin Board
  145.           System (BBS), including commercial systems such as
  146.           CompuServe (CIS), Genie, and BIX.  GAP_LIST may be
  147.           distributed by diskette by any organization or disk
  148.           distributor as long as the fee for this distribution is no
  149.           greater than $5 and it is made clear to the purchaser that
  150.           the distribution fee is NOT the same as the registration
  151.           fee.
  152.           
  153.           Feel free to pass around copies of GAP_LIST, however, please
  154.           distribute all of the original files and do not modify any
  155.           of the files.
  156.           
  157.           
  158.           
  159.           Enough with the BS, how do I use this thing?
  160.           --------------------------------------------
  161.           
  162.           The command-line syntax for GAP_LIST is very simple.  It
  163.           REQUIRES one parameter - the name of the controlling
  164.           configuration file.
  165.           
  166.               GAP_LIST <configuration filename>
  167.           
  168.           Example:
  169.           
  170.               GAP_LIST C:\GAP\GAP_LIST.PRM
  171.           
  172.           GAP_LIST will produce a listing of your GAP filebase
  173.           according to the specifications you provide in the
  174.           configuration file.  This is where things get just a bit
  175.           trickier.  (You might want to print out the sample
  176.           configuration file and keep it close by for rference as you
  177.           read the following.) GAP_LIST understands some very simple
  178.           commands that tell it which AREA/SUBJECT(s) to create
  179.           listings for, which listings to create, and where to put
  180.           them.
  181.           
  182.           There are several commands recognized by GAP_LIST: MAIN,
  183.           SEPARATOR, PRIVATE, FAST, MASTER, IGNORE, AREA, and SUBJECT.  
  184.           The MAIN command tells GAP_LIST where your GAP\MAIN directory 
  185.           is.  The SEPARATOR command is used to indicate how you want
  186.           individual file entries in the enhanced listings separated
  187.           -- with blank space or with a printable separator line.  The
  188.           PRIVATE command specifies the security level of private
  189.           files you don't want printed in the listings.  The MASTER
  190.           command is used to specify the names of master files that
  191.           will contain listings for every area and subject covered
  192.           during this run of GAP_LIST.  The IGNORE command is used to
  193.  
  194.  
  195.                                      Page 3                           
  196.  
  197.           GAP_LIST v1.3                                        4/17/93
  198.  
  199.  
  200.           indicate any files to be excluded from the new file scan.
  201.           The AREA command is used to indicate which forums you want
  202.           included in the listings and what listings you want
  203.           generated for that forum.  The SUBJECT command gives you
  204.           control down to the individual subject over which files are
  205.           listed.
  206.           
  207.           Before we get into the details about each configuration
  208.           command, here's a brief sample configuration file for you to
  209.           refer to while reading the command descriptions.
  210.           
  211.              MAIN i:\gap\main
  212.              SEPARATOR -
  213.              PRIVATE 110
  214.              MASTER RAW files.lst BULLETIN blt11
  215.              IGNORE @list.xcl
  216.              AREA 0 GEN i:\gap\gen CONDENSED main.lst ENHANCED main.enh 
  217.                   NEW main.new 30 TITLE "The Cookie Jar Main Board" 
  218.              SUBJECT CONDENSED dir%03i.lst
  219.              AREA 2 GEN i:\gap\windows\gen CONDENSED windows.lst 
  220.                   ENHANCED windows.enh NEW windows.new 30
  221.                   TITLE "The Cookie Jar Windows Forum"
  222.              AREA 3 GEN i:\gap\graphics\gen CONDENSED graphics.lst 
  223.                   ENHANCED graphics.enh NEW graphics.new 30
  224.                   TITLE "The Cookie Jar Graphics Forum"
  225.              AREA 4 GEN i:\gap\program\gen CONDENSED program.lst 
  226.                   ENHANCED program.enh NEW program.new 30
  227.                   TITLE "The Cookie Jar Programming Forum"
  228.           
  229.           (The indented lines in the above example are continuations
  230.           of the previous line.  Line wrapping of this sort is NOT
  231.           allowed in the actual configuration file.  We were forced to
  232.           do it here because of the line length limitations of this
  233.           document.)
  234.           
  235.           The MAIN Command
  236.           ----------------
  237.           
  238.           Command Format:   MAIN <GAP\MAIN directory path>
  239.           
  240.           The MAIN command specifies the path to your GAP\MAIN 
  241.           directory.  If you run GAP_LIST from your GAP default 
  242.           directory, the MAIN command is not required.  If run from some 
  243.           other directory, the MAIN command must be included or GAP_LIST 
  244.           won't know where to look for the required files.
  245.           
  246.           
  247.           The SEPARATOR Command
  248.           ---------------------
  249.           
  250.           Command Format:   SEPARATOR [<separator character>]
  251.           
  252.           The SEPARATOR command (optional) specifies how GAP_LIST
  253.           should separate the individual file entries in the enhanced
  254.           listings.  The first non-blank character following the
  255.           SEPARATOR keyword is used to create a separator line.  The
  256.           command "SEPARATOR *" will cause a line of asterisks to be
  257.           printed between each entry in the enhanced listing.  If the
  258.  
  259.  
  260.                                      Page 4                           
  261.  
  262.           GAP_LIST v1.3                                        4/17/93
  263.  
  264.  
  265.           configuration file does not contain a SEPARATOR command, a
  266.           line of graphical single horizontal line characters is used.
  267.           Something like:
  268.           
  269.           ───────────────────────────────────────────────────────────
  270.           
  271.           If the SEPARATOR command is specified without a following
  272.           non-blank character, each entry in the enhanced listings
  273.           will be separated by two blank lines.  This behavior mimics
  274.           that of the enhanced listing created by the GAPFILE Master
  275.           Listing function.
  276.           
  277.           
  278.           The PRIVATE Command
  279.           -------------------
  280.           
  281.           Command Format:   PRIVATE <seclev>
  282.           
  283.           The PRIVATE command (optional) specifies the security level
  284.           of private files that should not be included in the
  285.           listings.  Any file with a security level greater than or
  286.           equal to the specified level will not be included in the
  287.           listings.  If the PRIVATE command is not used, a default
  288.           private level of 110 will be used.
  289.           
  290.           
  291.           The FAST Command 
  292.           ----------------
  293.           
  294.           Command Format:   FAST
  295.           
  296.           GAP_LIST normally will write to the console status information
  297.           on the progress of the run.  This status information includes
  298.           the names of the files being generated, the total number of
  299.           files and bytes processed, and the data for the file currently
  300.           being processed.  The FAST command (optional, registered
  301.           version only) instructs GAP_LIST to update the status display
  302.           only at the end of a subject, not continually while processing
  303.           the files in that subject.  If you're in a real big hurry to
  304.           get the listings finished and don't mind long periods with no
  305.           positive indication that something is actually happening,
  306.           using the FAST command will marginally improve the execution
  307.           speed.  (This command is really a holdover from previous
  308.           versions when the screen output was much slower than in the
  309.           current verison.  You might see an improvement of a couple
  310.           percent in the execution speed, but it's really not worth
  311.           giving up the feedback for.)
  312.           
  313.           
  314.           The MASTER Command
  315.           ------------------
  316.           
  317.           Command Format:   MASTER [CONDENSED <filename>] 
  318.                                [ENHANCED <filename>] [RAW <filename>]
  319.                                [NEW <filename> <days>] 
  320.                                [BULLETIN <filename>]
  321.           
  322.           The MASTER command (optional) is used to specify listing
  323.  
  324.  
  325.                                      Page 5                           
  326.  
  327.           GAP_LIST v1.3                                        4/17/93
  328.  
  329.  
  330.           files that will contain all files listed by GAP_LIST in all
  331.           AREAs and SUBJECTs.  The MASTER command accepts several
  332.           sub-commands.  All the sub-commands must be on the same line
  333.           as the MASTER command.  There is no limit to the length of
  334.           the line.  All the sub-commands and their associated
  335.           parameters must be separated by one or more spaces.
  336.           
  337.           You may have more than one MASTER command in your
  338.           configuration file, but only the last occurrence of any
  339.           sub-command will have effect.  For instance, if your
  340.           configuration file contained the following lines
  341.           
  342.                MASTER ENHANCED master.enh CONDENSED master.lst
  343.                MASTER ENHANCED main.enh
  344.           
  345.           the CONDENSED sub-command from the first MASTER command
  346.           would still be in effect, but the ENHANCED sub-command from
  347.           the second MASTER command will override the ENHANCED
  348.           sub-command in the first line.
  349.           
  350.           
  351.           
  352.           
  353.           CONDENSED Sub-Command (MASTER)
  354.           ------------------------------
  355.           
  356.           Sub-Command Format: CONDENSED <filename>
  357.           
  358.           This is an optional sub-command that indicates you want a
  359.           condensed (one line per file) listing of all AREAs and
  360.           SUBJECTs specified in the configuration file.  This is
  361.           essentially the same as specifying CONDENSED files for each
  362.           AREA and then pasting all those files together.  <filename>
  363.           indicates where you want the listing to go.  <filename> may
  364.           be a relative (..\all.lst) or absolute
  365.           (c:\gap\filelist\all.lst) file specification.  You must
  366.           specify a filename following the CONDENSED sub-command.
  367.           
  368.           Example:  MASTER CONDENSED c:\gap\filelist\all.lst
  369.           
  370.           
  371.           ENHANCED Sub-Command (MASTER) 
  372.           -----------------------------
  373.                                                   
  374.           Sub-Command Format:  ENHANCED <filename>
  375.           
  376.           This is an optional sub-command that indicates you want an
  377.           enhanced (complete file information) listing of all AREAs
  378.           and SUBJECTs specified in the configuration file.
  379.           <filename> indicates where you want the listing to go.
  380.           <filename> may be a relative or absolute file specification.
  381.           You must specify a filename following the ENHANCED
  382.           sub-command.
  383.           
  384.           Example: MASTER ENHANCED c:\gap\filelist\all.enh
  385.           
  386.           
  387.           NEW Sub-Command (MASTER)
  388.  
  389.  
  390.                                      Page 6                           
  391.  
  392.           GAP_LIST v1.3                                        4/17/93
  393.  
  394.  
  395.           ------------------------
  396.           
  397.           Sub-Command Format: NEW <filename> <days>
  398.           
  399.           This is an optional sub-command (registered version only)
  400.           that indicates you want a condensed (one line per file)
  401.           listing of all files that are new within the last <days>
  402.           days in all AREAs and SUBJECTs specified in the
  403.           configuration file.  <filename> indicates where you want the
  404.           listing to go.  <filename> may be a relative (..\all.lst) or
  405.           absolute (c:\gap\filelist\all.lst) file specification.  You
  406.           must specify a filename following the NEW sub-command.
  407.           <days> indicates how far back to go when including files in
  408.           the NEW listing.  The specified number of days will be
  409.           subtracted from the current date and all files uploaded on
  410.           or after that date will be included in the NEW listing.  You
  411.           must specify a number of days after the <filename>.  <days>
  412.           can be any positive value less than 32,767.
  413.           
  414.           Example:  MASTER NEW c:\gap\filelist\new.lst
  415.           
  416.           
  417.           RAW Sub-Command (MASTER)
  418.           ------------------------
  419.           
  420.           Sub-Command Format:  RAW <filename>
  421.           
  422.           This is an optional sub-command that indicates you want a
  423.           raw listing of all the filenames in the AREAs and SUBJECTs
  424.           specified in the configuration file.  This is primarily for
  425.           use with protocols like HS/Link that can use such a file to
  426.           check for duplicates prior to accepting uploads.  <filename>
  427.           indicates where you want the listing to go.  <filename> may
  428.           be a relative or absolute file specification.  You must
  429.           specify a filename following the RAW sub-command.
  430.           
  431.           Note for those running a multi-node setup: If any of your
  432.           nodes are online while you're running GAP_LIST, be sure to
  433.           have GAP_LIST use a temporary file for the RAW listing and
  434.           then copy this temporary over the file normally accessed by
  435.           HS/Link.  If you send the RAW listing output to the same
  436.           file used by HS/Link to check for duplicates, you'll get a
  437.           sharing violation if someone uploads with HS/Link while
  438.           you're running GAP_LIST.
  439.           
  440.           The RAW sub-command can also be used with the AREA and
  441.           SUBJECT commands, but it will be most useful with the MASTER
  442.           command.
  443.           
  444.           
  445.           BULLETIN Sub-Command (MASTER) 
  446.           -----------------------------
  447.                                                   
  448.           Sub-Command Format:  BULLETIN <filename>
  449.           
  450.           This is an optional sub-command that indicates you want
  451.           GAP_LIST to create a summary bulletin listing the total
  452.           number of files and bytes in each AREA and SUBJECT specified
  453.  
  454.  
  455.                                      Page 7                           
  456.  
  457.           GAP_LIST v1.3                                        4/17/93
  458.  
  459.  
  460.           in the configuration file.  The bulletin file is formatted
  461.           to 80 columns and uses ANSI color.  A grand total of all files
  462.           listed, along with total bytes, is printed at the very bottom
  463.           of the bulletin.
  464.           
  465.           Example: MASTER BULLETIN c:\gap\gen\blt12
  466.           
  467.           
  468.           The IGNORE Command
  469.           -------------------
  470.           
  471.           The IGNORE command (recognized by registered version only)
  472.           is used to specify any files that should not be considered
  473.           when determining the newest file in an area or subject.  To
  474.           provide maximum execution speed, GAP_LIST will only generate
  475.           a listing for an area or subject if there are new files
  476.           present in that area or subject.  (The demo version does not
  477.           include this feature.  It will generate listings for all
  478.           requested areas/subjects whether there are new files or
  479.           not.)  It compares the date of the existing listing file (if
  480.           one does exist) to the date of the most recent file in the
  481.           area/subject in question.  If the listing file was generated
  482.           after the date of the most recent file, a new listing will
  483.           not be generated.  This prevents GAP_LIST from reproducing
  484.           the same listing over and over for an area/subject that has
  485.           had no uploads.
  486.           
  487.           The only catch is that if you update the filebase everytime
  488.           you run GAP_LIST, you'll always have at least one new file
  489.           (the newly generated listing file) the next time you run
  490.           GAP_LIST.  By using the IGNORE command, you can tell
  491.           GAP_LIST to ignore your listing files when determining the
  492.           date of the newest file in an area/subject.  So if the
  493.           listing file is the only new file in an area, a listing for
  494.           that area will not be generated.
  495.           
  496.           The IGNORE command is interpreted slightly differently
  497.           depending on where it occurs in the configuration file.  An
  498.           IGNORE command that occurs before the first AREA command
  499.           defines a list of files that will be ignored for the entire
  500.           filebase.  An IGNORE command that occurs after an AREA
  501.           command defines a list of files that will be ignored only for
  502.           the area defined by the preceeding AREA command.
  503.           
  504.           Command Format:   IGNORE [@<filelist>] [<filename>]
  505.           
  506.           The IGNORE command will accept any number of filenames.  If
  507.           a filename is preceeded by a @, that file will be assumed to
  508.           contain a list of filenames to be ignored, one name per line.
  509.           Any number of IGNORE commands can be specified in the
  510.           configuration file.
  511.           
  512.           Note, the IGNORE command is used only when determining the
  513.           newest file in an area.  It does NOT control which files are
  514.           included if a listing is generated.
  515.           
  516.           
  517.           The AREA Command
  518.  
  519.  
  520.                                      Page 8                           
  521.  
  522.           GAP_LIST v1.3                                        4/17/93
  523.  
  524.  
  525.           ----------------
  526.           
  527.           The AREA command (at least one required) is used to specify
  528.           which area(s) (forums) you want listings for.  The AREA
  529.           command requires one parameter, the area (forum) number, and
  530.           one sub-command, GEN.  It also accepts several optional
  531.           sub-commands.  All the sub-commands must be on the same line
  532.           as the AREA command.  There is no limit to the length of the
  533.           line.  All the sub-commands and their associated parameters
  534.           must be separated by one or more spaces.
  535.           
  536.           Command Format:   AREA <area #> [GEN <GEN path>]
  537.                               [CONDENSED <filename>] 
  538.                               [ENHANCED <filename>]
  539.                               [RAW <filename>] 
  540.                               [NEW <filename> <days>]
  541.                               [BULLETIN <filename>]                    
  542.                               [TITLE "<area title>"]
  543.           
  544.           The <area #> is the number of the forum to be listed.  The
  545.           main board is area 0 (zero).  You may have any number of
  546.           AREA commands in your configuration file, each on a separate
  547.           line.
  548.           
  549.           
  550.           GEN Sub-Command (AREA)
  551.           ----------------------
  552.           
  553.           Sub-Command Format:  GEN <path to AREA GEN directory>
  554.           
  555.           The GEN sub-command that specifies the path to the GAP GEN 
  556.           directory for this area.  GAP_LIST uses the GEN path to 
  557.           extract subject names from the GAP DIRS file and to determine 
  558.           how many subjects there are in a given area.  The extracted 
  559.           subject names will be used in headers for the subject 
  560.           listings.
  561.           
  562.           If GAP_LIST is run from the GAP default directory, the GEN 
  563.           command is not necessary as GAP_LIST will extract all required 
  564.           information from the GAP configuration files.  If run from 
  565.           some other directory, the GEN command is required.
  566.           
  567.           Example: AREA 0 GEN c:\gap\gen
  568.           
  569.           
  570.           CONDENSED Sub-Command (AREA)
  571.           ----------------------------
  572.           
  573.           Sub-Command Format:  CONDENSED <filename>
  574.           
  575.           This is an optional sub-command that indicates you want a
  576.           condensed (one line per file) listing of the associated
  577.           area.  <filename> indicates where you want the listing to
  578.           go.  <filename> may be a relative or absolute file
  579.           specification.  You must specify a filename following the
  580.           CONDENSED sub-command.
  581.           
  582.           Example:  AREA 0 GEN c:\gap\gen CONDENSED c:\gap\main.lst
  583.  
  584.  
  585.                                      Page 9                           
  586.  
  587.           GAP_LIST v1.3                                        4/17/93
  588.  
  589.  
  590.           
  591.           Files from all subjects in the specified area will be
  592.           included in the generated listings unless overridden by the
  593.           SUBJECT command.  (See below for details on the SUBJECT
  594.           command.)
  595.           
  596.           
  597.           ENHANCED Sub-Command (AREA)
  598.           ---------------------------
  599.                                                                             
  600.           Sub-Command Format:  ENHANCED <filename>
  601.           
  602.           This is an optional sub-command that indicates you want an
  603.           enhanced (complete file information) listing of the
  604.           associated area.  <filename> indicates where you want the
  605.           listing to go.  <filename> may be a relative or absolute
  606.           file specification.  You must specify a filename following
  607.           the ENHANCED sub-command.
  608.           
  609.           Example: AREA 0 GEN c:\gap\gen ENHANCED c:\gap\main.enh
  610.           
  611.           Files from all subjects in the specified area will be
  612.           included in the generated listings unless overridden by the
  613.           SUBJECT command.  (See below for details on the SUBJECT
  614.           command.)
  615.           
  616.           
  617.           NEW Sub-Command (AREA)
  618.           ----------------------
  619.           
  620.           Sub-Command Format: NEW <filename> <days>
  621.           
  622.           This is an optional sub-command (registered version only)
  623.           that indicates you want a condensed (one line per file)
  624.           listing of all files that are new within the last <days>
  625.           days in the associated area.  <filename> indicates where you
  626.           want the listing to go.  You must specify a filename
  627.           following the NEW sub-command.  <days> indicates how far
  628.           back to go when including files in the NEW listing.  The
  629.           specified number of days will be subtracted from the current
  630.           date and all files uploaded on or after that date will be
  631.           included in the NEW listing.  You must specify a number of
  632.           days after the <filename>.  <days> can be any positive value
  633.           less than 32,767.
  634.           
  635.           Example:  MASTER NEW c:\gap\filelist\new.lst
  636.           
  637.           
  638.           RAW Sub-Command (AREA)
  639.           ----------------------
  640.           
  641.           Sub-Command Format:  RAW <filename>
  642.           
  643.           This is an optional sub-command that indicates you want a
  644.           raw listing of all the filenames for this AREA.  This is
  645.           primarily for use with protocols like HS/Link that can use
  646.           such a file to check for duplicates prior to accepting
  647.           uploads.  <filename> indicates where you want to listing to
  648.  
  649.  
  650.                                     Page 10                           
  651.  
  652.           GAP_LIST v1.3                                        4/17/93
  653.  
  654.  
  655.           go.  <filename> may be a relative or absolute file
  656.           specification.  You must specify a filename following the
  657.           RAW sub-command.
  658.           
  659.           Example: AREA 0 GEN c:\gap\gen RAW c:\gap\files.lst
  660.           
  661.           Files from all subjects in the specified area will be
  662.           included in the generated listings unless overridden by the
  663.           SUBJECT command.  (See below for details on the SUBJECT
  664.           command.)
  665.           
  666.           
  667.           BULLETIN Sub-Command (AREA) 
  668.           ---------------------------
  669.                                                   
  670.           Sub-Command Format:  BULLETIN <filename>
  671.           
  672.           This is an optional sub-command that indicates you want
  673.           GAP_LIST to create a summary bulletin listing the total
  674.           number of files and bytes in each SUBJECT in this AREA.  The
  675.           bulletin file is formatted to 80 columns and uses ANSI
  676.           color.  A grand total of all files in this area is printed
  677.           at the very bottom of the bulletin.
  678.           
  679.           Example: AREA 0 GEN c:\gap\gen BULLETIN c:\gap\gen\blt11
  680.           
  681.           
  682.           TITLE Sub-Command (AREA)
  683.           ------------------------
  684.           
  685.           Sub-Command Format:  TITLE "<area title>"
  686.           
  687.           This is an optional sub-command that specifies a title for
  688.           the area.  This title will be printed in a double-line box
  689.           at the top of the listings for this area.  If no TITLE
  690.           sub-command is used, a generic title will be generated.  The
  691.           TITLE specified MUST be enclosed in quotes ("").
  692.           
  693.           Example: AREA 0 GEN c:\gap\gen TITLE "Main Board"
  694.           
  695.           
  696.           
  697.           The SUBJECT Command
  698.           -------------------
  699.           
  700.           The SUBJECT command (registered version only) is used to
  701.           override the inclusion of all subjects in an area or to
  702.           specify a filename template for individual subject listings.
  703.           If one of more SUBJECT commands which include a subject
  704.           number follow an AREA command, ONLY the subjects specified
  705.           by these commands will be included in the listings.
  706.           
  707.           The SUBJECT command can also be used to specify a filename
  708.           template for individual subject listings.  A SUBJECT command
  709.           that does not include a subject number specifies a template
  710.           and will not override the inclusion of all subjects for a
  711.           given area.
  712.           
  713.  
  714.  
  715.                                     Page 11                           
  716.  
  717.           GAP_LIST v1.3                                        4/17/93
  718.  
  719.  
  720.           The SUBJECT command accepts several sub-commands.  All the
  721.           sub-commands must be on the same line as the SUBJECT
  722.           command.  There is no limit to the length of the line.  All
  723.           the sub-commands and their associated parameters must be
  724.           separated by one or more spaces.
  725.           
  726.           
  727.           Command Format:  SUBJECT [<subject #>] 
  728.                              [CONDENSED <filename>]
  729.                              [ENHANCED <filename>] 
  730.                              [NEW <filename> <days>]
  731.                              [RAW <filename>]
  732.           
  733.           The optional <subject #> is the number of a subject
  734.           (directory) you want included with the listing for the
  735.           associated AREA.  Specifying a <subject #> with the SUBJECT
  736.           command will override the inclusion of all subjects in the
  737.           associated area.  All SUBJECT commands are associated with
  738.           the preceding AREA command.  You may have any number of
  739.           SUBJECT commands after an AREA command.  There may be only
  740.           one SUBJECT command on a line in the configuration file.
  741.           
  742.           Example: SUBJECT 1
  743.           
  744.           CONDENSED Sub-Command (SUBJECT)
  745.           -------------------------------
  746.           
  747.           Sub-Command Format:  CONDENSED <filename>
  748.           
  749.           This is an optional sub-command that indicates you want a
  750.           condensed (one line per file) listing of the associated
  751.           subject.  <filename> indicates where you want the listing to
  752.           go.  <filename> may be a relative (..\main.lst) or absolute
  753.           (c:\gap\filelist\main.lst) file specification.  You must
  754.           specify a filename following the CONDENSED sub-command.
  755.           
  756.           Example:  SUBJECT 1 CONDENSED c:\gap\dir1.lst 
  757.           
  758.           This SUBJECT command will override the inclusion of all
  759.           subjects in the associated AREA.  With this type of SUBJECT
  760.           command you must include a SUBJECT command for each subject
  761.           desired.
  762.           
  763.           Example:  SUBJECT CONDENSED c:\gap\dir%03i.lst
  764.           
  765.           This SUBJECT command specifies a filename template for
  766.           individual subject listings.  It does NOT override the
  767.           inclusion of all subjects in the associated AREA.  GAP_LIST
  768.           will use the specified file path/name as a template for the
  769.           individual subject listings.
  770.           
  771.           This template is in C printf format.  (If you aren't
  772.           familiar with this format, here's a brief explanation.  The
  773.           '%' sign indicates the beginning of a substitutable portion
  774.           of the string.  The '03' indicates that the substitutable
  775.           part is 3 characters long and should be padded on the left
  776.           with leading zeros.  The 'i' indicates the substitutable
  777.           parameter, in this case the subject number, is an integer.)
  778.  
  779.  
  780.                                     Page 12                           
  781.  
  782.           GAP_LIST v1.3                                        4/17/93
  783.  
  784.  
  785.           You can use any pattern you want for the filename, but be
  786.           sure the resulting filename will be legal.  GAP_LIST does no
  787.           error checking on the result and you may get very strange
  788.           results if your template doesn't generate a legal filename.
  789.           
  790.           The example above, c:\gap\dir%03i.lst, will generate files
  791.           DIR001.LST, DIR002.LST, DIR003.LST, etc.  in the C:\GAP
  792.           directory.  The template dir.%03i would generate files
  793.           DIR.001, DIR.002, DIR.003, etc.
  794.           
  795.           The SUBJECT CONDENSED listing is completely independent of
  796.           the AREA CONDENSED listing.  You may generate either or both
  797.           on any given run of GAP_LIST.
  798.           
  799.           
  800.           ENHANCED Sub-Command (SUBJECT)
  801.           ------------------------------
  802.           
  803.           Sub-Command Format:  ENHANCED <filename>
  804.           
  805.           This is an optional sub-command that indicates you want an
  806.           enhanced (complete file information) listing of the
  807.           associated subject.  <filename> indicates where you want the
  808.           listing to go.  <filename> may be a relative or absolute
  809.           file specification.  You must specify a filename following
  810.           the ENHANCED sub-command.
  811.           
  812.           Example: SUBJECT 1 ENHANCED c:\gap\dir1.enh
  813.           
  814.           This SUBJECT command will override the inclusion of all
  815.           subjects in the associated AREA.  With this type of SUBJECT
  816.           command you must include a SUBJECT command for each subject
  817.           desired.
  818.           
  819.           Example:  SUBJECT ENHANCED c:\gap\dir%03i.enh
  820.           
  821.           This SUBJECT command specifies a filename template for
  822.           individual subject listings.  It does NOT override the
  823.           inclusion of all subjects in the associated AREA.  GAP_LIST
  824.           will use the specified file path/name as a template for the
  825.           individual subject listings.  See the SUBJECT CONDENSED
  826.           Sub-command for an explanation of the template format.
  827.           
  828.           The SUBJECT ENHANCED listing is completely independent of
  829.           the AREA ENHANCED listing (or any of the CONDENSED
  830.           listings).  You may generate either or both (or all) on any
  831.           given run of GAP_LIST.
  832.           
  833.           NEW Sub-Command (SUBJECT)
  834.           -------------------------
  835.           
  836.           Sub-Command Format:  NEW <filename> <days>
  837.           
  838.           This is an optional sub-command that indicates you want a
  839.           condensed (one line per file) listing of all files that are
  840.           new within the last <days> days in the associated subject.
  841.           <filename> indicates where you want the listing to go.
  842.           <filename> may be a relative or absolute file specification.
  843.  
  844.  
  845.                                     Page 13                           
  846.  
  847.           GAP_LIST v1.3                                        4/17/93
  848.  
  849.  
  850.           You must specify a filename following the NEW sub-command.
  851.           <days> indicates how far back to go when including files in
  852.           the NEW listing.  The specified number of days will be
  853.           subtracted from the current date and all files uploaded on
  854.           or after that date will be included in the NEW listing.  You
  855.           must specify a number of days after the <filename>.  <days>
  856.           can be any positive value less than 32,767.
  857.           
  858.           Example: SUBJECT 1 NEW c:\gap\dir1.new
  859.           
  860.           This SUBJECT command will override the inclusion of all
  861.           subjects in the associated AREA.  With this type of SUBJECT
  862.           command you must include a SUBJECT command for each subject
  863.           desired.
  864.           
  865.           Example:  SUBJECT NEW c:\gap\dir%03i.new
  866.           
  867.           This SUBJECT command specifies a filename template for
  868.           individual subject listings.  It does NOT override the
  869.           inclusion of all subjects in the associated AREA.  GAP_LIST
  870.           will use the specified file path/name as a template for the
  871.           individual subject listings.  See the SUBJECT CONDENSED
  872.           Sub-command for an explanation of the template format.
  873.           
  874.           The SUBJECT NEW listing is completely independent of
  875.           the AREA NEW listing (or any of the CONDENSED or ENHANCED
  876.           listings).  You may generate either or both (or all) on any
  877.           given run of GAP_LIST.
  878.           
  879.           
  880.           RAW Sub-Command (AREA)
  881.           ----------------------
  882.           
  883.           Sub-Command Format:  RAW <filename>
  884.           
  885.           This is an optional sub-command that indicates you want a
  886.           raw listing of all the filenames in this SUBJECT.  This is
  887.           primarily for use with protocols like HS/Link that can use
  888.           such a file to check for duplicates prior to accepting
  889.           uploads.  <filename> indicates where you want to listing to
  890.           go.  <filename> may be a relative or absolute file
  891.           specification.  You must specify a filename following the
  892.           RAW sub-command.
  893.           
  894.           The RAW sub-command follows the same general format as the
  895.           SUBJECT CONDENSED and SUBJECT ENHANCED sub-commands.  If the
  896.           SUBJECT command contains a subject number it will override
  897.           the inclusion of all subjects in the associated area.  If
  898.           the SUBJECT command does not include a subject number, the
  899.           RAW filename will be used as a template to generate raw
  900.           listing filenames for each subject in the associated area.
  901.           
  902.           
  903.           
  904.           
  905.           How about some real world examples?
  906.           -----------------------------------
  907.           
  908.  
  909.  
  910.                                     Page 14                           
  911.  
  912.           GAP_LIST v1.3                                        4/17/93
  913.  
  914.  
  915.           Let's take my GAP board as an example.  I have files in my
  916.           main board and in the Windows Forum (forum #2), the Graphics
  917.           Forum (forum #3), and the Programming Forum (forum #4).
  918.           
  919.           I want to generate condensed and enhanced listings for all
  920.           the subjects in the main board, the Windows forum, and the
  921.           graphics forum.  I want a listing of the main board files
  922.           that are new within the last 30 days.  I want individual
  923.           condensed listings for each of the subject in the main
  924.           board.  I want listings for the programming forum, but only
  925.           for subjects 1 and 2. I also want to generate a raw listing
  926.           of all these files for use with the HS/Link batch upload
  927.           checker.  Here's a GAP_LIST configuration file that will do
  928.           this.  (NOTE: In the following example some of the command
  929.           lines would not fit within the margins of this document so
  930.           they have been split onto multiple lines.  This is not
  931.           allowed in an actual GAP_LIST parameter file.  The wrapped
  932.           parts of the command lines are indented and have an asterisk
  933.           (*) in the first column.)
  934.           
  935.           MAIN i:\gap\main
  936.           PRIVATE 110
  937.           SEPARATOR -
  938.           IGNORE main_lst.zip main_enh.zip win_lst.zip win_enh.zip
  939.           IGNORE grph_lst.zip grph_enh.zip prgm_lst.zip prgm_enh.zip
  940.           IGNORE dir001.zip dir002.zip dir003.zip dir004.zip
  941.           IGNORE dir005.zip dir006.zip dir007.zip dir008.zip
  942.           IGNORE dir009.zip dir010.zip dir011.zip dir012.zip
  943.           MASTER RAW c:\gap\files\files.lst
  944.           AREA 0 CONDENSED main.lst ENHANCED main.enh NEW main.new 30
  945.           *     GEN gen  TITLE "The Cookie Jar Main Board Files"
  946.           SUBJECT CONDENSED dir%03i.lst
  947.           AREA 2 CONDENSED windows.lst ENHANCED windows.enh 
  948.           *     TITLE "The Cookie Jar Windows Forum" 
  949.           *     GEN c:\gap\windows\gen
  950.           AREA 3 CONDENSED graphics.lst ENHANCED graphics.enh
  951.           *     TITLE "The Cookie Jar Graphics Forum"
  952.           *     GEN c:\gap\graphics\gen
  953.           AREA 4 CONDENSED program.lst ENHANCED program.enh
  954.           *     TITLE "The Cookie Jar Programming Forum"
  955.           *     GEN c:\gap\program\gen
  956.           SUBJECT 1
  957.           SUBJECT 2
  958.           
  959.           
  960.           Limitations
  961.           -----------
  962.           
  963.           When configured to generate the maximum number of listings,
  964.           GAP_LIST opens a lot of files at the same time.  If you
  965.           start getting "Can't open file" messages, be sure you have
  966.           your FILES= in your CONFIG.SYS set to at least 30.
  967.           (FILES=30)
  968.           
  969.           The demo version of GAP_LIST has the following limitations:
  970.           
  971.              1) Single-node operation only.  Do NOT attempt to run 
  972.                 the demo version on a multi-node system when any of
  973.  
  974.  
  975.                                     Page 15                           
  976.  
  977.           GAP_LIST v1.3                                        4/17/93
  978.  
  979.  
  980.                 the nodes are active!
  981.              2) No individual subject listings.
  982.              3) No NEW file listings.
  983.              4) No FAST output command.
  984.              5) All listings will be generated everytime the program
  985.                 is run.  Only the registered version contains the
  986.                 ability to generate a listing only if there are new
  987.                 files in an area/subject.
  988.              6) Listings will be marked as having been generated by an
  989.                 unregistered copy of GAP_LIST.
  990.              7) A ticker-tape of beg messages and ads for other GAP-Pro
  991.                 programs will stream across the bottom of the screen
  992.                 while GAP_LIST is running.  This slows execution down a
  993.                 bit, though it really isn't significant.
  994.           
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.                                     Page 16                           
  1041.